OpenEdge Application Server:<br />Developing AppServer Applications Progress 4GL for programming AppServer client procedures

Table 3–1 lists the Progress 4GL elements that are either valid only for accessing an AppServer connection or have special application in AppServer client programming. The remaining sections in this chapter explain how to use these elements.

Table 3–1: Progress 4GL for programming AppServer procedures
4GL element	Description
ASYNC-REQUEST-COUNT	1) An `INTEGER` attribute on the server object handle that returns the number of active asynchronous requests submitted to this server. 2) An `INTEGER` attribute on the procedure handle that returns the number of currently outstanding asynchronous requests for this procedure. Can be non-zero only if the `PROXY` and `PERSISTENT` attributes are both set to `TRUE`.
Asynchronous request object handle	A type of handle that maintains the status of an asynchronous request in a Progress 4GL client application. This handle provides methods and attributes that allow you to check the status of a remote procedure (internal or external) that is called asynchronously.
CANCELLED	A `LOGICAL` attribute on the asynchronous request object handle that indicates if the asynchronous request was cancelled using either the `CANCEL-REQUESTS( )` method or the `DISCONNECT( )` method on the associated server handle.
CANCEL-REQUESTS( )	A method on the server object handle that for a session-managed application raises a `STOP` condition in the context of the currently running asynchronous request and purges the send queue of any asynchronous requests that have not been executed. For a session-free application, it causes a `STOP` condition to be raised for all currently running asynchronous requests, and purges the send queue of any asynchronous requests that have not been executed.
CLIENT-CONNECTION-ID	A `CHARACTER` attribute on the server object handle that for a session-managed application returns the connection ID for the physical AppServer connection associated with this server handle. For a session-free application, the connection is a binding to an application service that relies on a pool of AppServer connections to service all requests from the client; because there is no single physical connection between the client and an AppServer, this attribute returns the Unknown value (`?`).
COMPLETE	A `LOGICAL` attribute on the asynchronous request object handle that indicates if the asynchronous request is completed and its result is processed on the client.
CONNECT( [ `connection-parameters` ] [ , `userid` ] [ , `password` ] [ , `appserver-info` ] )	A method on the server object handle that physically connects and associates an AppServer instance or logically connects an application service with the server handle.
CONNECTED( )	A method on the server object handle that returns `TRUE` for a session-managed application if an AppServer is currently connected and associated with the server handle. For a session-free application it returns `TRUE` if the `CONNECT( )` method has been successfully executed for an application service associated with this handle and at least one AppServer resource is available for the client to access this application service.
CREATE SERVER `server-handle`	A statement that creates a server object handle and stores it in a `HANDLE` variable.
DEFINE INPUT PARAMETER `parameter`	A statement for defining `INPUT` parameters within an event procedure. Each `INPUT` parameter must correspond to an `OUTPUT` or `INPUT-OUTPUT` parameter of the associated asynchronous remote procedure.
DELETE OBJECT `handle`	A statement that you can use to delete certain objects, including server objects, and persistent procedures (local and remote), and asynchronous request objects.
DELETE PROCEDURE `procedure-handle`	A statement that you can use to delete both local and remote procedure objects (persistent procedures).
DISCONNECT( )	A method on the server object handle that disconnects from and removes all reference to the AppServer currently associated with the server handle. Any running or pending asynchronous requests submitted by this client are also cancelled.
ERROR	A `LOGICAL` attribute on the asynchronous request object handle that indicates that an `ERROR` condition was returned from the AppServer as a result of processing the request.
EVENT-PROCEDURE	A `CHARACTER` attribute on the asynchronous request object handle that contains the name of the internal procedure to be run as the event procedure for this asynchronous request.
EVENT-PROCEDURE-CONTEXT	A `HANDLE` attribute on the asynchronous request object handle that contains the procedure handle of the active procedure context where the event procedure for this asynchronous request is defined.
FIRST-ASYNC-REQUEST( )	A method on the server object handle that returns the first entry in the list of all current asynchronous request handles for the specified AppServer.
FIRST-PROCEDURE	A `HANDLE` attribute on the server object handle that returns the first entry in the list of remote persistent procedures running on the connected AppServer.
FIRST-SERVER	A `HANDLE` attribute on the `SESSION` system handle that returns the handle to the first entry in the chain of server handles for the session.
FUNCTION ... IN `procedure-handle`	A statement that defines a forward reference to a remote user-defined function prototype. When `procedure-handle` is a proxy persistent procedure handle, the function is defined on the connected AppServer in the specified procedure object.
LAST-ASYNC-REQUEST( )	A method on the server object handle that returns the last entry in the list of all current asynchronous request handles for the specified AppServer.
LAST-PROCEDURE	A `HANDLE` attribute on the server object handle that returns the last entry in the list of remote persistent procedures running on the connected AppServer.
LAST-SERVER	A `HANDLE` attribute on the `SESSION` system handle that returns the handle to the last entry in the chain of server handles for the session.
NAME	A `CHARACTER` attribute on the server object handle that uniquely identifies the AppServer for use in the Application Debugger. For a session-managed application, it returns the connection ID for the AppServer associated with the server handle. For a session-free application, it returns the connection ID of the first AppServer connection created in the connection pool with this server handle when the application service is first bound using the `CONNECT( )` method.
NEXT-SIBLING	1) A `HANDLE` attribute on the server object handle that returns the next entry in the list of server handles created for the current Progress 4GL session. 2) A `HANDLE` attribute on the proxy persistent procedure handle that returns the next entry in the list of proxy persistent procedure handles. 3) A `HANDLE` attribute on the asynchronous request object handle that returns the next entry in the list of asynchronous request handles for asynchronous remote procedures submitted for execution on the same AppServer.
PERSISTENT	A `LOGICAL` attribute on procedure handles and the `THIS-PROCEDURE` system handle that is `TRUE` if the specified procedure is running persistently as a procedure object.
PERSISTENT-PROCEDURE	A `HANDLE` attribute on the asynchronous request object handle that returns the proxy persistent procedure handle to the remote persistent procedure that contains the internal procedure executed for the specified asynchronous request. If the request is for an external, rather than an internal, procedure, this attribute returns an invalid handle.
PREV-SIBLING	1) A `HANDLE` attribute on the server object handle that returns the previous entry in the list of server handles created for the current Progress 4GL session. 2) A `HANDLE` attribute on the proxy persistent procedure handle that returns the previous entry in the list of proxy persistent procedure handles. 3) A `HANDLE` attribute on the asynchronous request object handle that returns the previous entry in the list of asynchronous request handles for asynchronous remote procedures submitted for execution on the same AppServer.
PROCEDURE-COMPLETE	The event returned for an asynchronous request object handle that indicates the associated remote procedure has completed execution and, as a result, causes execution of the specified event procedure as specified by the `EVENT-PROCEDURE` and `EVENT-PROCEDURE-CONTEXT` attributes.
PROCEDURE-NAME	A `CHARACTER` attribute on the asynchronous request object handle that provides the name of the remote procedure executed to instantiate this asynchronous request handle.
PROCESS EVENTS	A statement that you can use to handle any pending `PROCEDURE-COMPLETE` events for asynchronous requests. You can also use any blocking I/O statement, such as the `WAIT-FOR` statement.
PROXY	A `LOGICAL` attribute on procedure handles that is `TRUE` if the procedure handle is a proxy handle for a persistent procedure running remotely in the context of an AppServer.
Proxy persistent procedure handle	A type of procedure object handle that references the context of a remote persistent procedure, providing access to its remote internal procedures and user-defined functions.
QUIT	A `LOGICAL` attribute on the asynchronous request object handle that indicates a `QUIT` condition was returned from the AppServer as a result of processing the request.
RUN ... [PERSISTENT ...] ON [SERVER] `server-handle` [TRANSACTION DISTINCT] [ASYNCHRONOUS ...] ...	The statement that executes an external (remote) procedure on a connected AppServer specified by `server-handle`, in a transaction that is distinct from the client. With the `PERSISTENT` option, it instantiates the procedure as a persistent procedure object. With the `ASYNCHRONOUS` option, the procedure executes asynchronously with respect to the client. This option also optionally specifies the associated asynchronous request handle and event procedure to handle results of the request. If `server-handle` is the `SESSION` system handle, the external procedure executes synchronously in the local session.
RUN ... IN `procedure-handle` [ASYNCHRONOUS ...] ...	The statement that executes an internal (remote) procedure on a connected AppServer, where `procedure-handle` specifies a remote persistent procedure that is instantiated on the AppServer and that defines the internal procedure. With the `ASYNCHRONOUS` option, the internal procedure executes asynchronously with respect to the client. This option also optionally specifies the associated asynchronous request handle and event procedure to handle results of the request. If `procedure-handle` is the handle to a local persistent procedure, the internal procedure executes synchronously in the local session.
SELF	A system handle that, in the context of an event procedure, returns the asynchronous request object handle of the completed request for which the event procedure is executing.
SERVER	1) A `HANDLE` attribute on a remote persistent procedure handle that returns the server object handle to the AppServer on which the specified remote persistent procedure runs. Valid only if the `PROXY` and `PERSISTENT` attributes are both `TRUE`. 2) A `HANDLE` attribute on the asynchronous request object handle that returns the server handle of the AppServer where this asynchronous request was submitted for execution. If the request is run in the local session (using the `SESSION` system handle), the attribute is set to `SESSION`.
Server object handle	A type of handle that provides a connection to an AppServer in a Progress 4GL client application. This handle provides server object methods and attributes that allow you to connect and manage an AppServer.
SSL-SERVER-NAME	A `CHARACTER` attribute on the socket object handle that returns the SSL server’s X.500 Subject name field after any SSL session has been established.
STOP	A `LOGICAL` attribute on the asynchronous request object handle that indicates a `STOP` condition was returned from the AppServer as a result of processing the request.
TYPE	1) A `CHARACTER` attribute on the server object handle that returns the handle type, which is `"SERVER"` for a server object handle. 2) A `CHARACTER` attribute on the asynchronous request object handle that provides the handle type, which is `"ASYNC-REQUEST"` for an asynchronous request object handle.
WAIT-FOR ...	A statement that you can use to handle any pending `PROCEDURE-COMPLETE` events for asynchronous requests. You can also use `PROCESS` `EVENTS` or any other blocking I/O statement, such as the `PROMPT-FOR` statement.